|
PATH Mac OS 8 and 9 Developer Documentation
> Human Interface Toolbox
> Dialog Manager
>
|
Mac OS 8 Dialog Manager Reference
|
|
|
|
PATHMac OS 8 and 9 Developer Documentation
> Human Interface Toolbox
> Dialog Manager
>
|
|
Mac OS 8 Dialog Manager Reference
|
The following Dialog Manager functions for creating alert boxes are new, changed, or not recommended with Appearance Manager 1.0:
Displays a standard alert box.
pascal OSErr StandardAlert (
AlertType inAlertType,
StringPtr inError,
StringPtr inExplanation,
AlertStdAlertParamPtr inAlertParam,
SInt16 *outItemHit);
The StandardAlert function displays an alert box based on the values you pass it. You can pass the error text you wish displayed in the error and explanation parameters, and customize the alert button text by filling in the appropriate fields of the standard alert structure passed in the inAlertParam parameter.
StandardAlert automatically resizes the height of a dialog box to fit all static text. It ignores alert stages and therefore provides no corresponding alert sounds.
Displays an alert box and/or plays an alert sound.
pascal short Alert (short alertID,
ModalFilterUPP modalFilter);
The Alert function displays an alert box or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box. The Alert function creates the alert defined in the specified alert resource and its corresponding extended alert resource. The function calls the current alert sound function and passes it the sound number specified in the alert resource for the current alert stage. If no alert box is to be drawn at this stage, Alert returns -1; otherwise, it uses the NewDialog function to create and display the alert box. The default system window colors are used unless your application provides an alert color table resource with the same resource ID as the alert resource. The Alert function uses the ModalDialog function to get and handle most events for you.
The Alert function does not display a default icon in the upper-left corner of the alert box; you can leave this area blank, or you can specify your own icon in the alert's item list resource, which in turn is specified in the alert resource.
The Alert function continues calling ModalDialog until the user selects an enabled control (typically a button), at which time the Alert function removes the alert box from the screen and returns the item number of the selected control. Your application then responds as appropriate when the user clicks this item.
If you need to display an alert box while your application is running in the background or is otherwise invisible to the user, call AEInteractWithUser ; see Inside Macintosh: Interapplication Communication.
The Dialog Manager uses the system alert sound as the error sound unless you change it by calling the ErrorSound function .
Displays an alert box with a stop icon and/or plays an alert sound.
pascal short StopAlert (short alertID, ModalFilterUPP modalFilter);
The StopAlert function displays an alert box with a stop icon in its upper-left corner or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box.
The StopAlert function is the same as the Alert function Alert except that, before drawing the items in the alert box, StopAlert draws the stop icon in the upper-left corner. The stop icon has resource ID 0, which you can also specify with the constant stopIcon . By default, the Dialog Manager uses the standard stop icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 0.
Use a stop alert to inform the user that a problem or situation is so serious that the action cannot be completed. Stop alerts typically have only a single button (OK), because all the user can do is acknowledge that the action cannot be completed.
IMPORTANT
Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the StopAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call StopAlert .
Displays an alert box with a note icon and/or plays an alert sound.
pascal short NoteAlert (
short alertID,
ModalFilterUPP modalFilter);
The NoteAlert function displays an alert box with a note icon in its upper-left corner or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box.
The NoteAlert function is the same as the Alert function except that, before drawing the items in the alert box, NoteAlert draws the note icon in the upper-left corner. The note icon has resource ID 1, which you can also specify with the constant noteIcon . By default, the Dialog Manager uses the standard note icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 1.
Use a note alert to inform users of a minor mistake that won't have any disastrous consequences if left as is. Usually this type of alert simply offers information, and the user responds by clicking an OK button. Occasionally, a note alert may ask a simple question and provide a choice of responses.
IMPORTANT
Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the NoteAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call NoteAlert .
Displays an alert box with a caution icon and/or plays an alert sound.
pascal short CautionAlert (
short alertID,
ModalFilterUPP modalFilter);
Displays an alert box with a caution icon in its upper-left corner or, if appropriate for the alert stage, to play an alert sound instead of or in addition to displaying the alert box.
The CautionAlert function is the same as the Alert function except that, before drawing the items in the alert box, CautionAlert draws the caution icon in the upper-left corner. The caution icon has resource ID 2, which you can also specify with the constant kCautionIcon . By default, the Dialog Manager uses the standard caution icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 2.
Use a caution alert to alert the user of an operation that may have undesirable results if it's allowed to continue. Give the user the choice of continuing the action (by clicking an OK button) or stopping it (by clicking a Cancel button).
IMPORTANT
Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the CautionAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call CautionAlert .